Callback
Unlike request-based methods that are initiated by the integrator, the callback is initiated by the Keepz payment system. The integrator must implement an endpoint to receive and handle these callbacks.
The purpose of the callback is to deliver real-time updates about the payment status, specifically when:
- The payment has been completed successfully.
- The payment has failed or was not completed.
Payment details are sent to the callback URL using the POST method. The callback URL can be provided in two ways:
- Dynamic – passed during order creation.
- Static – configured once during integration with Keepz.
To confirm successful receipt of the callback, the integrator must return HTTP status code 200.
If the callback is not received successfully, the integrator should use the Get Order Status method to verify the payment status and update the order status in its system accordingly.
Callback Parameters
| Parameter | Type | Possible Values / Format | Description |
|---|---|---|---|
amount | number | Amount paid by the customer in the transaction. | |
receiverId | string (UUID v4) | Unique identifier of the receiver in Keepz system. | |
receiverType | string | BRANCH | Type of the receiver. |
integratorId | string (UUID v4) | Unique identifier of the integrator in Keepz system. | |
integratorOrderId | string (UUID v4) | Unique identifier of the order in the integrator’s system, provided during order creation. | |
status | string | SUCCESS, FAILED | Current status of the order. |
cardInfo | object | Card details if the payment was made with a bank card. Returned only if saveCard = true and the integrator has permission. See details below. | |
initialCurrency | string | USD, EUR, GEL | Currency displayed to the sender as requested by the integrator. |
acquiringCurrency | string | USD, EUR, GEL, | Currency in which the payment is acquired. Only returned if enabled for the integrator by Keepz. |
acquiringAmount | number | Amount processed in the acquiring currency. Only returned if enabled for the integrator by Keepz. |
Card info Object
| Field | Type | Possible Values / Format | Description |
|---|---|---|---|
token | string(UUID v4) | Tokenized card identifier. Can be reused by the integrator for future orders (via cardToken). | |
provider | string | CREDO | Payment provider that processed the card transaction. |
cardMask | string | Masked PAN (e.g., 411111******1111) | Masked card number. |
expirationDate | string | Format MM/YY (e.g., 12/27) | Card expiration date. |
cardBrand | string | VISA, MasterCard, AMEX, etc. | Brand of the card. |